package de.jmda.gen.java;

import javax.validation.constraints.NotNull;

import de.jmda.gen.CompoundGenerator;

/**
 * Interface for generators that produce Java declarations of packages, types,
 * fields or methods. A Java declaration consists of a (maybe empty)
 * documentation (see {@link #getJavaDocGenerator()}), a (maybe empty) set
 * of annotation statements (see {@link #getAnnotationStatementsGenerator()})
 * and a non empty, complete element declaration (see {@link
 * #getDeclaredElementGenerator()}).
 *
 * @author roger.jmda@gmail.com
 */
public interface DeclarationGenerator extends CompoundGenerator
{
	/**
	 * @return <code>Generator</code> that provides (maybe empty) documentation
	 *         for the Java element declaration that is produced by
	 *         implementations of this interface.
	 */
	JavaDocGenerator getJavaDocGenerator();

	/**
	 * @param generator
	 * @see #getJavaDocGenerator()
	 */
	void setJavaDocGenerator(JavaDocGenerator generator);

	/**
	 * @NotNull
	 * @return non null java doc generator
	 */
	JavaDocGenerator demandJavaDocGenerator();

	/**
	 * @return <code>Generator</code> that provides (maybe empty) annotation
	 *         statements for the Java element declaration that is produced by
	 *         implementations of this interface.
	 */
	AnnotationStatementsGenerator getAnnotationStatementsGenerator();

	/**
	 * @param generator
	 * @see #getAnnotationStatementsGenerator()
	 */
	void setAnnotationStatementsGenerator(AnnotationStatementsGenerator generator);

	/**
	 * @NotNull
	 * @return non null annotation statements generator
	 */
	AnnotationStatementsGenerator demandAnnotationStatementsGenerator();

	/**
	 * @return Generator that produces the complete technical (non JavaDoc) part
	 *         of a Java element declaration.
	 */
	@NotNull DeclaredElementGenerator getDeclaredElementGenerator();
	
	// <G extends DeclaredElementGenerator> void setDeclaredElementGenerator(@NotNull G generator);
	
	// setDeclaredElementGenerator is intended to be strictly typed for
	// implementing classes without using generics, so no setter declaration here.
}